
                                       dfttest v1.5 by tritical

Info:

   2D/3D frequency domain denoiser.

   Requires libfftw3f-3.dll to be in the search path.
   http://www.fftw.org/install/windows.html


syntax:

   dfttest(bool Y, bool U, bool V, int ftype, float sigma, float sigma2, float pmin,
           float pmax, int sbsize, int smode, int sosize, int tbsize, int tmode,
           int tosize, int swin, int twin, float sbeta, float tbeta, bool zmean,
           string sfile, string sfile2, string pminfile, string pmaxfile, float f0beta,
           string nfile, int threads, int opt)


parameters:

   Y,U,V -

       If true, the corresponding plane is processed.  Otherwise, it is copied through
       to the output image as is.

       default:  true,true,true


   ftype -

       Controls the filter type.  Possible settings are:

           0 -  generalized wiener filter

                 mult = max((psd-sigma)/psd,0)^f0beta

           1 -  hard threshold

                 mult = psd < sigma ? 0.0 : 1.0;

           2 -  multiplier

                 mult = sigma

           3 -  multiplier switched based on psd value

                 mult = (psd >= pmin && psd <= pmax) ? sigma : sigma2

           4 -  multiplier modified based on psd value and range

                 mult = sigma*sqrt((psd*pmax)/((psd+pmin)*(psd+pmax)))

       The real and imaginary parts of each complex dft coefficient are multiplied
       by the corresponding 'mult' value.

          ** psd = magnitude squared = real*real + imag*imag

       default:  0


   sigma,sigma2 -

       Value of sigma and sigma2 (used as described in ftype parameter description).
       If using the sfile parameter then the sigma parameter is ignored.  If using
       the sfile2 parameter then the sigma2 parameter is ignored.

           NOTE:  Starting in v1.5, these values are normalized based on the
                  non-coherent power gain of the window when ftype<2.  That
                  is to say that for ftype<2, where sigma/sigma2 correspond 
                  to power, they are now independent of the window size and
                  windowing function used, and that they directly correspond
                  to power. For convenience, the normalization factor is output
                  using OutputDebugString() when the filter loads. To convert
                  between old and new sigma values, simply multiply the pre v1.5
                  sigma value by the scaling factor. This scaling is also
                  applied to values loaded from sfile/sfile2 files.

       default:  16.0,16.0


   pmin,pmax -

       Used as described in the ftype parameter description.  If using the pminfile
       parameter then the pmin parameter is ignored.  If using the pmaxfile parameter
       then the pmax parameter is ignored.

           NOTE:  Starting in v1.5, these values are normalized based on the
                  non-coherent power gain of the window. They are now independent
                  of the window size and windowing function used, and directly
                  correspond to power. For convenience, the normalization factor
                  is output using OutputDebugString() when the filter loads. To
                  convert between old and new pmin/pmax values, simply multiply
                  the pre v1.5 values by the scaling factor. This scaling is
                  also applied to values loaded from pmin/pmax files.

       default:  0.0,500.0


   sbsize -

       Sets the length of the sides of the spatial window.  Must be 1 or greater.
       Must be odd if using smode = 0.

       default:  12


   smode -

       Sets the mode for spatial operation.  There are two possible settings:

          0 -  process every pixel independently... center the spatial window
               on the current pixel, filter, move to the next pixel, repeat.
               Spatial overlapping 'sosize' not used.

          1 -  process the spatial dimension in blocks of sbsize.  Spatial
               overlapping 'sosize' used.

       default:  1


   sosize -

       Sets the spatial overlap amount.  Must be in the range 0 to sbsize-1 (inclusive).
       If sosize is greater than sbsize>>1, then sbsize%(sbsize-sosize) must equal 0.
       In other words, overlap greater than 50% requires that sbsize-sosize be a divisor
       of sbsize.

       default:  9


   tbsize -

       Sets the length of the temporal dimension (i.e. number of frames).  Must be at
       least 1.  Must be odd if using tmode = 0.

       default:  5


   tmode -

       Sets the mode for temporal operation.  There are two possible settings:

          0 -  process every frame independently... center the temporal window
               on the current frame, filter, move to the next frame, repeat.
               Temporal overlapping 'tosize' not used.

          1 -  process the temporal dimension in blocks of tbsize.  Temporal
               overlapping 'tosize' used.  

       default:  0


   tosize -

       Sets the temporal overlap amount.  Must be in the range 0 to tbsize-1 (inclusive).
       If tosize is greater than tbsize>>1, then tbsize%(tbsize-tosize) must equal 0.
       In other words, overlap greater than 50% requires that tbsize-tosize be a divisor
       of tbsize.

       default:  0


   swin,twin -

       Sets the type of analysis/synthesis window to be used for spatial (swin) and
       temporal (twin) processing.  Possible settings:

		 0:  hanning
		 1:  hamming
		 2:  blackman
		 3:  4 term blackman-harris
		 4:  kaiser-bessel
		 5:  7 term blackman-harris
		 6:  flat top
		 7:  rectangular
		 8:  Bartlett
		 9:  Bartlett-Hann
		10:  Nuttall
		11:  Blackman-Nuttall

       default:  0,0


   sbeta,tbeta -

       Sets the beta value for kaiser-bessel window type.  sbeta goes with swin,
       tbeta goes with twin.  Not used unless the corresponding window value
       is set to 4.

       default:  2.5,2.5


   zmean -

       Controls whether the window mean is subtracted out (zero'd) prior to
       filtering in the frequency domain.

       default:  true


   sfile -

       Specifies an input file listing sigma values for each dft coefficient.
       There can be multiple lines with multiple coefficients per line.
       Separate coefficients on the same line using ','.  The coefficients
       are read from the file in left to right, top to bottom order.

       The dft transform results in tbsize*sbsize*((sbsize>>1)+1) coefficients.
       You must give these many sigma values in the sfile.  Assuming 2D (tbsize=1),
       and sbsize=8 (i.e. 8x8 window).  The resulting dft transform has 40
       coefficients organized as follows:

              0  1  2  3  4
              5  6  7  8  9
             10 11 12 13 14
             15 16 17 18 19
             20 21 22 23 24
             25 26 27 28 29
             30 31 32 33 34
             35 36 37 38 39

       The number given here specifies which sigma value from the sfile
       corresponds to that dft coefficient.

       The DC coefficient is in the upper left.  The top row corresponds to
       purely horizontal frequencies, and the frequencies increase from left to
       right. In this example '4' corresponds to the highest horizontal frequency.

       The left-most column corresponds to purely vertical frequencies, but the
       highest frequency is at the (sbsize>>1) row (assuming the numbering starts
       at 0)... in this case '20' corresponds to the highest vertical frequency.
       The frequencies then decrease from (sbsize>>1) to sbsize-1.  Basically,
       the first (sbsize>>1) rows correspond to the positive frequencies and
       the last (sbsize>>1)-1 rows correspond to the negative frequencies.

       In the 8x8 case, the single highest frequency is located at '24'.

       In the case that tbsize > 1, the first set of ((sbsize>>1)+1)*sbsize
       cofficients correspond to the lowest frequencies temporally (with the
       relations described for the 2D case holding within that set) and the
       frequencies increase temporally from set to set up to the tbsize>>1 set.
       The frequencies then decrease from there to the tbsize-1 set (again
       the positive vs negative frequencies as mentioned previously). If tbsize=3,
       you get 120 coefficients:

              0   1   2   3   4
              5   6   7   8   9
             10  11  12  13  14
             15  16  17  18  19
             20  21  22  23  24
             25  26  27  28  29
             30  31  32  33  34
             35  36  37  38  39

             40  41  42  43  44
             45  46  47  48  49
             50  51  52  53  54
             55  56  57  58  59
             60  61  62  63  64
             65  66  67  68  69
             70  71  72  73  74
             75  76  77  78  79

             80  81  82  83  84
             85  86  87  88  89
             90  91  92  93  94
             95  96  97  98  99
            100 101 102 103 104
            105 106 107 108 109
            110 111 112 113 114
            115 116 117 118 119

       The DC coefficient is still at '0'.  The highest purely temporal frequency is
       at '40'.  The highest overall frequency is at '64'.

       default:  ""


   sfile2,pminfile,pmaxfile -

       Can be used to give different values of sigma2, pmin, and pmax for each
       dft coefficient respectively.  Entry and format is exactly the same as
       described in the sfile parameter description.  If sfile2 is not given then
       the value of sigma2 is used for every dft coefficient.  If pminfile is
       not given then the value of pmin is used for every dft coefficient.  If
       pmaxfile is not given then the value of pmax is used for every dft coefficient.

       default:  "","",""


   f0beta -

       Power term in ftype=0. The ftype=0 formula is:

              max((psd-sigma)/psd,0)^f0beta

       For f0beta=1, this equation corresponds to the wiener filter with
       spectral subtraction as the estimate of the signal power. For f0beta=0.5,
       the equation corresponds to spectral subtraction. The 1.0 and 0.5 cases
       are separated from the general routine in the code to allow for fast
       operation. Other values will result in the general routine being used,
       which has to perform a pow() computation, and is therefore much slower.

       default:  1.0


   nfile -

       When ftype<2, a nfile can be used to specify block locations in the video
       from which dfttest will estimate the noise power spectrum (sigma) to
       be used for filtering.

       When the noise to be removed is not white (i.e. doesn't have a flat power
       spectrum), specifying only a single sigma value is not adequate. Prior
       to v1.5, using dfftest in such cases meant you would have to figure out the
       noise spectrum on your own, and then use an sfile to input the sigma values.
       Now dfttest can perform the task of estimating the noise spectrum.

       The nfile should list locations in the video that consist of noise on
       a flat background, one entry per line. The line syntax is:

                 frame_number,plane,ypos,xpos   e.g.  0,0,20,20

           plane:  (0=Y,1=U,2=V)
           ypos/xpos:  the upper left position of the block
                       (0,0 is the upper left of the frame)

           dfttest positions a window (of the type defined by sbsize/tbsize/swin/twin)
           at the specified location, and estimates the power using fft magnitude^2.
           When tbsize>1, frame_number specifies the first frame of the temporal block.
           Make sure that the window size is large enough to capture the full noise
           pattern.

           If you list multiple blocks (multiple lines in the nfile), then the
           estimates obtained at each block are averaged to form the final estimate.
           Having more block locations to use lowers the variance of the estimate.
           When listing multiple block locations, it is best if the locations do
           not overlap.

           Typically, subtracting out the noise power spectrum is not adequate becase
           it is only the average. In any one block the noise spectrum has the potential
           to exceed the average in a frequency bin. Therefore, one typically over
           subtracts based on some multiple of the noise spectrum (usually in the range
           of 3-8). The default used in dfttest is 5 if ftype=0 and 7 if ftype=1. If you
           want to use another value, then on some line in the nfile put the following:

                  a=over_subtraction_factor   e.g.  a=3.5

           To comment out a line in a nfile (have it be ignored), place a '#' at the
           beginning of the line.

           An example:

              avisource("noisy_source.avi")
              dfttest(f0beta=0.5,U=false,V=false,nfile="nfile.txt")

                Here, dfftest is being used with default settings to filter only
                the Y plane, expect for f0beta=0.5 resulting in spectral subtraction
                instead of wiener filtering.  nfile is listing locations of only
                noise, and has the following lines:

                   0,0,20,40
                   5,0,100,380
                   14,0,400,100
                   a=5.2

                The first line corresponds to frame 0, y-plane, at x,y location (40,20).
                The estimate from that block will be averaged with the other two
                estimates, and the over subtraction factor is set equal to 5.2.

       When using a nfile, the estimated noise spectrum is output to 
       "noise_power_spectrum.txt", located in the current directory. It lists the
       power of each dft coefficient (layout is the same as explained in the sfile
       description). The average noise power is also calculated.

       default:  ""


   threads -

       Sets the number of threads used for processing.  If set to 0, then threads
       is set equal to the number of detected processors.

       default:  0


   opt -

       Sets which cpu optimizations are used.  Possible settings:

          0 - auto detect
          1 - c routines
          2 - sse routines
          3 - sse2 routines

       default:  0


Changes:

   04/11/2009  v1.5

       + added f0beta in ftype=0
       + added nfile parameter (noise power estimation)
       + normalization of sigma/sigma2/pmin/pmax based on non-coherent power gain

   04/06/2009  v1.4

       - fix threading issue that could result in corrupted output

   01/27/2009  v1.3

       + more assembly optimizations
       + tmode=1 caching (don't need to recalculate all involved temporal blocks on every frame)
       - replicate temporal dimension at beginning/end, don't mirror

   01/24/2009  v1.2

       + added filter types 3/4 and corresponding parameters (sigma2,pmin,pmax,
            sfile2,pminfile,pmaxfile)
       + more asm optimizations
       - fixed problem with global function pointers
       - changed name of 'cfile' parameter to 'sfile'
       - the value given for sigma is no longer squared on initialization
       - sigma now defaults to 2.0
       - tbsize now defaults to 5

   11/22/2007  v1.1

       + more sse optimizations
       - fixed a bug causing the bottom part of the frame to be incorrectly
            processed with some sbsize/sosize combinations

   11/21/2007  v1.0

       - initial release


contact:  forum.doom9.org - tritical  or  kes25c@mizzou.edu
